Conversation
✅ Deploy Preview for openapi-ts canceled.
|
|
size-limit report 📦
|
gzm0
left a comment
gzm0
left a comment
There was a problem hiding this comment.
TY for writing this. This LGTM modulo the bit about "one test" (but it feels we're in agreement and it's mostly wordsmithing).
| - It might be a `major` release if the example changes are thousands and thousands of lines (and the changes are complex and layered). | ||
| - It might be a `major` release if the output seems laterally-different, such as replacing `|` for `&`. | ||
|
|
||
| There’s more subjectivity to it than one realizes. In general, try and estimate how many people _may_ be impacted. Use the OpenAPI example specs as a reference—you can at least see how much it changes the output for a handful of real-world scenarios. Try and wait to ship sweeping, high-impact changes for major releases if at all possible. |
There was a problem hiding this comment.
It might make sense going forward to narrow down our guidelines w.r.t. this. For example: is a change requiring a newer typescript feature but clearly having better types a breaking change?
The main reason I think we should narrow down guidelines is because they not only matter for maintainers, but also for users. As a user I want to know what the library I use considers a breaking change.
All that being said, definitely not something that is actionable in the scope of this PR.
|
|
||
| For 0.x projects (which, again, no longer apply), we’d switch to use `patch` for any **backwards-compatible change** and `minor` for all **breaking changes** (i.e. disregard feature vs bug). | ||
|
|
||
| ## History |
There was a problem hiding this comment.
Nice! I think this section is super helpful. Good call writing that.
| Not to mention this library required changes to `openapi-typescript` core to generate the necessary types to make it possible. It resulted in learning the following lessons: | ||
|
|
||
| - **Pure `.d.ts`-only fetch clients are not valuable.** We’re talking _pure_-pure, which was what openapi-fetch was. There was no codegen, and it had zero runtime knowledge of your schema. Folks found this to be usable for simple cases, but inevitably as their project grew they did want an SDK that saved them from duplicating code. | ||
| - **Bad SDKs are still bad, though.** swagger-codegen and the like, generating a net-new function that just copy-pastes everything, is still a bad experience. openapi-fetch was ~3kb minified! Some bad SDKs can be 0.25MB-0.5MB or more in real-world cases. Half a megabyte of wasteful boilerplate. So there’s a balance her! |
There was a problem hiding this comment.
| - **Bad SDKs are still bad, though.** swagger-codegen and the like, generating a net-new function that just copy-pastes everything, is still a bad experience. openapi-fetch was ~3kb minified! Some bad SDKs can be 0.25MB-0.5MB or more in real-world cases. Half a megabyte of wasteful boilerplate. So there’s a balance her! | |
| - **Bad SDKs are still bad, though.** swagger-codegen and the like, generating a net-new function that just copy-pastes everything, is still a bad experience. openapi-fetch was ~3kb minified! Some bad SDKs can be 0.25MB-0.5MB or more in real-world cases. Half a megabyte of wasteful boilerplate. So there’s a balance here! |
3 participants
Changes
Adds docs for thoughts on how to review, how to release. General maintainer guidelines
How to Review
Read it!!! 🙏
Checklist
No, seriously, read it please and give feedback